SGI Freeware 1999 August/SGI Freeware 1999 August.iso/dist/fw_perl.idb/usr/freeware/catman/p_man/cat3/Math::Complex.Z/Math::Complex

Text File | 1998-10-28 | 19.4 KB | 595 lines

     MMMMaaaatttthhhh::::::::CCCCoooommmmpppplllleeeexxxx((((3333)))) 1111////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222)))) MMMMaaaatttthhhh::::::::CCCCoooommmmpppplllleeeexxxx((((3333))))



     NNNNAAAAMMMMEEEE
      Math::Complex    - complex numbers and associated mathematical
      functions

     SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
          use Math::Complex;

          $z = Math::Complex->make(5, 6);
          $t = 4 - 3*i + $z;
          $j = cplxe(1,    2*pi/3);


     DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
      This package lets you    create and manipulate complex numbers.
      By default, _P_e_r_l limits itself to real numbers, but an extra
      use statement    brings full complex support, along with    a full
      set of mathematical functions    typically associated with
      and/or extended to complex numbers.

      If you wonder    what complex numbers are, they were invented
      to be    able to    solve the following equation:

          x*x =    -1

      and by definition, the solution is noted _i (engineers    use _j
      instead since    _i usually denotes an intensity,    but the    name
      does not matter). The    number _i is a pure _i_m_a_g_i_n_a_r_y number.

      The arithmetics with pure imaginary numbers works just like
      you would expect it with real    numbers... you just have to
      remember that

          i*i =    -1

      so you have:

          5i + 7i = i *    (5 + 7)    = 12i
          4i - 3i = i *    (4 - 3)    = i
          4i * 2i = -8
          6i / 2i = 3
          1 / i    = -i

      Complex numbers are numbers that have    both a real part and
      an imaginary part, and are usually noted:

          a + bi

      where    a is the _r_e_a_l part and b is the    _i_m_a_g_i_n_a_r_y part.    The
      arithmetic with complex numbers is straightforward. You have
      to keep track    of the real and    the imaginary parts, but
      otherwise the    rules used for real numbers just apply:




     Page 1                        (printed 10/23/98)






     MMMMaaaatttthhhh::::::::CCCCoooommmmpppplllleeeexxxx((((3333)))) 1111////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222)))) MMMMaaaatttthhhh::::::::CCCCoooommmmpppplllleeeexxxx((((3333))))



          (4 + 3i) + (5    - 2i) =    (4 + 5)    + i(3 -    2) = 9 + i
          (2 + i) * (4 - i) = 2*4 + 4i -2i -i*i    = 8 + 2i + 1 = 9 + 2i

      A graphical representation of    complex    numbers    is possible in
      a plane (also    called the _c_o_m_p_l_e_x _p_l_a_n_e, but it's really a 2D
      plane).  The number

          z = a    + bi

      is the point whose coordinates are (a, b). Actually, it
      would    be the vector originating from (0, 0) to (a, b). It
      follows that the addition of two complex numbers is a
      vectorial addition.

      Since    there is a bijection between a point in    the 2D plane
      and a    complex    number (i.e. the mapping is unique and
      reciprocal), a complex number    can also be uniquely
      identified with polar    coordinates:

          [rho,    theta]

      where    rho is the distance to the origin, and theta the angle
      between the vector and the _x axis. There is a    notation for
      this using the exponential form, which is:

          rho *    exp(i *    theta)

      where    _i is the famous    imaginary number introduced above.
      Conversion between this form and the cartesian form a    + bi
      is immediate:

          a = rho * cos(theta)
          b = rho * sin(theta)

      which    is also    expressed by this formula:

          z = rho * exp(i * theta) = rho * (cos    theta +    i * sin    theta)

      In other words, it's the projection of the vector onto the _x
      and _y    axes. Mathematicians call _r_h_o the _n_o_r_m or _m_o_d_u_l_u_s and
      _t_h_e_t_a    the _a_r_g_u_m_e_n_t of    the complex number. The    _n_o_r_m of    z will
      be noted abs(z).

      The polar notation (also known as the    trigonometric
      representation) is much more handy for performing
      multiplications and divisions    of complex numbers, whilst the
      cartesian notation is    better suited for additions and
      subtractions.    Real numbers are on the    _x axis,    and therefore
      _t_h_e_t_a    is zero    or _p_i.

      All the common operations that can be    performed on a real
      number have been defined to work on complex numbers as well,



     Page 2                        (printed 10/23/98)






     MMMMaaaatttthhhh::::::::CCCCoooommmmpppplllleeeexxxx((((3333)))) 1111////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222)))) MMMMaaaatttthhhh::::::::CCCCoooommmmpppplllleeeexxxx((((3333))))



      and are merely _e_x_t_e_n_s_i_o_n_s of the operations defined on real
      numbers. This    means they keep    their natural meaning when
      there    is no imaginary    part, provided the number is within
      their    definition set.

      For instance,    the sqrt routine which computes    the square
      root of its argument is only defined for non-negative    real
      numbers and yields a non-negative real number    (it is an
      application from RRRR++++ to RRRR++++).  If we allow it to return    a
      complex number, then it can be extended to negative real
      numbers to become an application from    RRRR to CCCC (the set    of
      complex numbers):

          sqrt(x) = x >= 0 ? sqrt(x) : sqrt(-x)*i

      It can also be extended to be    an application from CCCC to CCCC,
      whilst its restriction to RRRR behaves as defined above by
      using    the following definition:

          sqrt(z = [r,t]) = sqrt(r) * exp(i * t/2)

      Indeed, a negative real number can be    noted [x,pi] (the
      modulus _x is always non-negative, so [x,pi] is really    -x, a
      negative number) and the above definition states that

          sqrt([x,pi]) = sqrt(x) * exp(i*pi/2) = [sqrt(x),pi/2]    = sqrt(x)*i

      which    is exactly what    we had defined for negative real
      numbers above.  The sqrt returns only    one of the solutions:
      if you want the both,    use the    root function.

      All the common mathematical functions    defined    on real
      numbers that are extended to complex numbers share that same
      property of working _a_s _u_s_u_a_l when the    imaginary part is zero
      (otherwise, it would not be called an    extension, would it?).

      A _n_e_w    operation possible on a    complex    number that is the
      identity for real numbers is called the _c_o_n_j_u_g_a_t_e, and is
      noted    with an    horizontal bar above the number, or ~z here.

           z = a + bi
          ~z = a - bi

      Simple... Now    look:

          z * ~z = (a +    bi) * (a - bi) = a*a + b*b

      We saw that the norm of z was    noted abs(z) and was defined
      as the distance to the origin, also known as:

          rho =    abs(z) = sqrt(a*a + b*b)




     Page 3                        (printed 10/23/98)






     MMMMaaaatttthhhh::::::::CCCCoooommmmpppplllleeeexxxx((((3333)))) 1111////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222)))) MMMMaaaatttthhhh::::::::CCCCoooommmmpppplllleeeexxxx((((3333))))



      so

          z * ~z = abs(z) ** 2

      If z is a pure real number (i.e. b ==    0), then the above
      yields:

          a * a    = abs(a) ** 2

      which    is true    (abs has the regular meaning for real number,
      i.e. stands for the absolute value). This example explains
      why the norm of z is noted abs(z): it    extends    the abs
      function to complex numbers, yet is the regular abs we know
      when the complex number actually has no imaginary part...
      This justifies _a _p_o_s_t_e_r_i_o_r_i our use of the abs notation for
      the norm.

     OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNNSSSS
      Given    the following notations:

          z1 = a + bi =    r1 * exp(i * t1)
          z2 = c + di =    r2 * exp(i * t2)
          z = <any complex or real number>

      the following    (overloaded) operations    are supported on
      complex numbers:

          z1 + z2 = (a + c) + i(b + d)
          z1 - z2 = (a - c) + i(b - d)
          z1 * z2 = (r1    * r2) *    exp(i *    (t1 + t2))
          z1 / z2 = (r1    / r2) *    exp(i *    (t1 - t2))
          z1 **    z2 = exp(z2 * log z1)
          ~z = a - bi
          abs(z) = r1 =    sqrt(a*a + b*b)
          sqrt(z) = sqrt(r1) * exp(i * t/2)
          exp(z) = exp(a) * exp(i * b)
          log(z) = log(r1) + i*t
          sin(z) = 1/2i    (exp(i * z1) - exp(-i *    z))
          cos(z) = 1/2 (exp(i *    z1) + exp(-i * z))
          atan2(z1, z2)    = atan(z1/z2)

      The following    extra operations are supported on both real
      and complex numbers:

          Re(z)    = a
          Im(z)    = b
          arg(z) = t
          abs(z) = r

          cbrt(z) = z ** (1/3)
          log10(z) = log(z) / log(10)
          logn(z, n) = log(z) /    log(n)



     Page 4                        (printed 10/23/98)






     MMMMaaaatttthhhh::::::::CCCCoooommmmpppplllleeeexxxx((((3333)))) 1111////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222)))) MMMMaaaatttthhhh::::::::CCCCoooommmmpppplllleeeexxxx((((3333))))



          tan(z) = sin(z) / cos(z)

          csc(z) = 1 / sin(z)
          sec(z) = 1 / cos(z)
          cot(z) = 1 / tan(z)

          asin(z) = -i * log(i*z + sqrt(1-z*z))
          acos(z) = -i * log(z + i*sqrt(1-z*z))
          atan(z) = i/2    * log((i+z) / (i-z))

          acsc(z) = asin(1 / z)
          asec(z) = acos(1 / z)
          acot(z) = atan(1 / z)    = -i/2 * log((i+z) / (z-i))

          sinh(z) = 1/2    (exp(z)    - exp(-z))
          cosh(z) = 1/2    (exp(z)    + exp(-z))
          tanh(z) = sinh(z) / cosh(z) =    (exp(z)    - exp(-z)) / (exp(z) + exp(-z))

          csch(z) = 1 /    sinh(z)
          sech(z) = 1 /    cosh(z)
          coth(z) = 1 /    tanh(z)

          asinh(z) = log(z + sqrt(z*z+1))
          acosh(z) = log(z + sqrt(z*z-1))
          atanh(z) = 1/2 * log((1+z) / (1-z))

          acsch(z) = asinh(1 / z)
          asech(z) = acosh(1 / z)
          acoth(z) = atanh(1 / z) = 1/2    * log((1+z) / (z-1))

      _a_r_g, _a_b_s, _l_o_g, _c_s_c, _c_o_t, _a_c_s_c, _a_c_o_t, _c_s_c_h, _c_o_t_h, _a_c_o_s_e_c_h,
      _a_c_o_t_a_n_h, have    aliases    _r_h_o, _t_h_e_t_a, _l_n,    _c_o_s_e_c, _c_o_t_a_n, _a_c_o_s_e_c,
      _a_c_o_t_a_n, _c_o_s_e_c_h, _c_o_t_a_n_h, _a_c_o_s_e_c_h, _a_c_o_t_a_n_h, respectively.  Re,
      Im, arg, abs,    rho, and theta can be used also    also mutators.
      The cbrt returns only    one of the solutions: if you want all
      three, use the root function.

      The _r_o_o_t function is available to compute all    the _n roots of
      some complex,    where _n    is a strictly positive integer.     There
      are exactly _n    such roots, returned as    a list.    Getting    the
      number mathematicians    call j such that:

          1 + j    + j*j =    0;

      is a simple matter of    writing:

          $j = ((root(1, 3))[1];

      The _kth root for z = [r,t] is    given by:

          (root(z, n))[k] = r**(1/n) * exp(i * (t + 2*k*pi)/n)




     Page 5                        (printed 10/23/98)






     MMMMaaaatttthhhh::::::::CCCCoooommmmpppplllleeeexxxx((((3333)))) 1111////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222)))) MMMMaaaatttthhhh::::::::CCCCoooommmmpppplllleeeexxxx((((3333))))



      The _s_p_a_c_e_s_h_i_p    comparison operator, <=>, is also defined. In
      order    to ensure its restriction to real numbers is conform
      to what you would expect, the    comparison is run on the real
      part of the complex number first, and    imaginary parts    are
      compared only    when the real parts match.

     CCCCRRRREEEEAAAATTTTIIIIOOOONNNN
      To create a complex number, use either:

          $z = Math::Complex->make(3, 4);
          $z = cplx(3, 4);

      if you know the cartesian form of the    number,    or

          $z = 3 + 4*i;

      if you like. To create a number using    the polar form,    use
      either:

          $z = Math::Complex->emake(5, pi/3);
          $x = cplxe(5,    pi/3);

      instead. The first argument is the modulus, the second is
      the angle (in    radians, the full circle is 2*pi).  (Mnemonic:
      e is used as a notation for complex numbers in the polar
      form).

      It is    possible to write:

          $x = cplxe(-3, pi/4);

      but that will    be silently converted into [3,-3pi/4], since
      the modulus must be non-negative (it represents the distance
      to the origin    in the complex plane).

      It is    also possible to have a    complex    number as either
      argument of either the make or emake:    the appropriate
      component of the argument will be used.

          $z1 =    cplx(-2,  1);
          $z2 =    cplx($z1, 4);


     SSSSTTTTRRRRIIIINNNNGGGGIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN
      When printed,    a complex number is usually shown under    its
      cartesian form _a+_b_i, but there are legitimate    cases where
      the polar format [_r,_t] is more appropriate.

      By calling the routine Math::Complex::display_format and
      supplying either "polar" or "cartesian", you override    the
      default display format, which    is "cartesian".    Not supplying
      any argument returns the current setting.



     Page 6                        (printed 10/23/98)






     MMMMaaaatttthhhh::::::::CCCCoooommmmpppplllleeeexxxx((((3333)))) 1111////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222)))) MMMMaaaatttthhhh::::::::CCCCoooommmmpppplllleeeexxxx((((3333))))



      This default can be overridden on a per-number basis by
      calling the display_format method instead. As    before,    not
      supplying any    argument returns the current display format
      for this number. Otherwise whatever you specify will be the
      new display format for _t_h_i_s particular number.

      For instance:

          use Math::Complex;

          Math::Complex::display_format('polar');
          $j = ((root(1, 3))[1];
          print    "j = $j\n";          # Prints "j =    [1,2pi/3]
          $j->display_format('cartesian');
          print    "j = $j\n";          # Prints "j =    -0.5+0.866025403784439i"

      The polar format attempts to emphasize arguments like    _k*_p_i/_n
      (where _n is a    positive integer and _k an integer within
      [-9,+9]).

     UUUUSSSSAAAAGGGGEEEE
      Thanks to overloading, the handling of arithmetics with
      complex numbers is simple and    almost transparent.

      Here are some    examples:

          use Math::Complex;

          $j = cplxe(1,    2*pi/3);  # $j ** 3 == 1
          print    "j = $j, j**3 =    ", $j ** 3, "\n";
          print    "1 + j + j**2 =    ", 1 + $j + $j**2, "\n";

          $z = -16 + 0*i;          # Force it to    be a complex
          print    "sqrt($z) = ", sqrt($z), "\n";

          $k = exp(i * 2*pi/3);
          print    "$j - $k = ", $j - $k, "\n";

          $z->Re(3);              # Re,    Im, arg, abs,
          $j->arg(2);              # (the last two aka rho, theta)
                          # can    be used    also as    mutators.


     EEEERRRRRRRROOOORRRRSSSS DDDDUUUUEEEE    TTTTOOOO DDDDIIIIVVVVIIIISSSSIIIIOOOONNNN BBBBYYYY ZZZZEEEERRRROOOO OOOORRRR LLLLOOOOGGGGAAAARRRRIIIITTTTHHHHMMMM OOOOFFFF ZZZZEEEERRRROOOO
      The division (/) and the following functions

          log      ln      log10      logn
          tan      sec      csc      cot
          atan      asec      acsc      acot
          tanh      sech      csch      coth
          atanh      asech      acsch      acoth




     Page 7                        (printed 10/23/98)






     MMMMaaaatttthhhh::::::::CCCCoooommmmpppplllleeeexxxx((((3333)))) 1111////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222)))) MMMMaaaatttthhhh::::::::CCCCoooommmmpppplllleeeexxxx((((3333))))



      cannot be computed for all arguments because that would mean
      dividing by zero or taking logarithm of zero.    These
      situations cause fatal runtime errors    looking    like this

          cot(0): Division by zero.
          (Because in the definition of    cot(0),    the divisor sin(0) is 0)
          Died at ...

      or

          atanh(-1): Logarithm of zero.
          Died at...

      For the csc, cot, asec, acsc,    acot, csch, coth, asech,
      acsch, the argument cannot be    0 (zero).  For the the
      logarithmic functions    and the    atanh, acoth, the argument
      cannot be 1 (one).  For the atanh, acoth, the    argument
      cannot be -1 (minus one).  For the atan, acot, the argument
      cannot be i (the imaginary unit).  For the atan, acoth, the
      argument cannot be -i    (the negative imaginary    unit).    For
      the tan, sec,    tanh, the argument cannot be _p_i/_2 + _k *    _p_i,
      where    _k is any integer.

      Note that because we are operating on    approximations of real
      numbers, these errors    can happen when    merely `too close' to
      the singularities listed above.  For example
      tan(2*atan2(1,1)+1e-15) will die of division by zero.

     EEEERRRRRRRROOOORRRRSSSS DDDDUUUUEEEE    TTTTOOOO IIIINNNNDDDDIIIIGGGGEEEESSSSTTTTIIIIBBBBLLLLEEEE    AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
      The make and emake accept both real and complex arguments.
      When they cannot recognize the arguments they    will die with
      error    messages like the following

          Math::Complex::make: Cannot take real part of ...
          Math::Complex::make: Cannot take real part of ...
          Math::Complex::emake: Cannot take    rho of ...
          Math::Complex::emake: Cannot take    theta of ...


     BBBBUUUUGGGGSSSS
      Saying use Math::Complex; exports many mathematical routines
      in the caller    environment and    even overrides some (sqrt,
      log).     This is construed as a    feature    by the Authors,
      actually... ;-)

      All routines expect to be given real or complex numbers.
      Don't    attempt    to use BigFloat, since Perl has    currently no
      rule to disambiguate a '+' operation (for instance) between
      two overloaded entities.

      In Cray UNICOS there is some strange numerical instability
      that results in _r_o_o_t(), _c_o_s(), _s_i_n(),    _c_o_s_h(),    _s_i_n_h(),    losing



     Page 8                        (printed 10/23/98)






     MMMMaaaatttthhhh::::::::CCCCoooommmmpppplllleeeexxxx((((3333)))) 1111////AAAAuuuugggg////99998888 ((((ppppeeeerrrrllll 5555....000000005555,,,, ppppaaaattttcccchhhh 00002222)))) MMMMaaaatttthhhh::::::::CCCCoooommmmpppplllleeeexxxx((((3333))))



      accuracy fast.  Beware.  The bug may be in UNICOS math libs,
      in UNICOS C compiler,    in Math::Complex.  Whatever it is, it
      does not manifest itself anywhere else where Perl runs.

     AAAAUUUUTTTTHHHHOOOORRRRSSSS
      Raphael Manfredi <_R_a_p_h_a_e_l__M_a_n_f_r_e_d_i@_g_r_e_n_o_b_l_e._h_p._c_o_m> and
      Jarkko Hietaniemi <_j_h_i@_i_k_i._f_i>.

      Extensive patches by Daniel S. Lewart    <_d-_l_e_w_a_r_t@_u_i_u_c._e_d_u>.














































     Page 9                        (printed 10/23/98)